fix(io): order image-directory frames naturally - #558
Open
AlexBodner wants to merge 1 commit into
Open
Conversation
`_iter_image_folder_frames` sorted entries lexicographically, so a directory of unpadded names was read as 1, 10, 11, 2, 3, ... The frames were then numbered sequentially, so a temporally shuffled sequence produced sequential frame ids and nonsense tracks with no error raised. Sorting on a natural key restores numeric order for unpadded names. Zero-padded and non-numeric names sort identically under both keys, so benchmark sequences are unaffected. No warning is emitted for mixed-width numeric names: natural ordering resolves them correctly, so a warning would fire on valid input. Co-authored-by: Cursor <cursoragent@cursor.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Adds natural filename ordering for image-directory frame sources.
Changes:
- Sorts embedded numeric filename segments numerically.
- Documents ordering behavior.
- Adds numeric, alphabetic, and zero-padded ordering tests.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
src/trackers/io/video.py |
Implements and documents natural sorting. |
tests/io/test_video.py |
Tests image-directory ordering behavior. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
+179
to
+186
| for index, stem in enumerate(("alpha", "beta", "gamma")): | ||
| cv2.imwrite(str(directory / f"{stem}.png"), create_frame(index)) | ||
|
|
||
| frames = list(frames_from_source(directory)) | ||
|
|
||
| assert len(frames) == 3 | ||
| for frame_id, frame in frames: | ||
| assert np.all(frame == expected_frame_value(frame_id - 1)) |
AlexBodner
marked this pull request as ready for review
August 18, 2026 22:03
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
_iter_image_folder_framessorts directory entries lexicographically, so1.jpg … 10.jpgis read as 1, 10, 11, 2, 3, … Frames are then numbered sequentially by enumeration, so a temporally shuffled sequence still gets sequential frame ids.Nothing raises. The tracker receives frames out of order, motion between consecutive frames is nonsense, and every track is garbage — with no indication why.
When this happens
Only through
frames_from_sourceon an image directory — the public API andtrackers track <dir>. The trigger is unpadded numeric filenames, which is whatffmpeg -i video.mp4 %d.jpgproduces.Not reported by anyone, and benchmarking can't hit it: MOT Challenge and DanceTrack frames are zero-padded (6- and 8-digit), and the eval path resolves frames by index through
resolve_mot_frame_pathrather than sorting a listing. Butio/frames.pyalready falls back to a plain-int stem — "Try both, then plain int" — so unpadded naming is a layout the library expects to meet.Fix
Sort on a natural key that compares embedded digit runs as integers. Zero-padded and non-numeric names sort identically under both keys, so benchmark sequences are unaffected.
Mixed-width numeric names get no warning: natural ordering resolves them correctly, so a warning would fire on valid input.
Tests
1.png…11.pngread in numeric order — fails before the change, where frame 2 returned the contents of10.png.test_reads_images_in_alphabetical_ordersince the contract is no longer alphabetical.tests/io+tests/cli: 341 passed.